Conversation
The NixOS instructions told readers not to manage agent.yaml with environment.etc, on the grounds that it "produces a read-only symlink into the Nix store, and the service refuses to start". The diagnosis was wrong and the advice ruled out the deployment NixOS users actually want. Neither the symlink nor the file mode was the problem. The unit gated on ConditionPathIsReadWrite=, which per systemd.unit(5) tests whether the underlying filesystem is mounted read-only, not whether the file is writable, and it resolves symlinks. NixOS remounts /nix/store read-only at boot, so the check landed there and skipped the unit. The agent itself reads a mode 0444 agent.yaml happily and never writes to it; everything it writes lives in /var/lib/step-agent. agent#1205 changes that gate to ConditionPathExists=, which is the question the unit meant to ask all along. So point readers at the declarative form instead, wired to the pre-registration flow that already documents where the team slug and CA fingerprint come from. Also refresh the troubleshooting callout for the new directive name, and say that older agents report the same check under the old one, so the message matches whichever version a reader has installed. Merge after agent#1205, which is what updates the step-agent.nix published to files.smallstep.com. Refs OFF-19. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RkEcowtxSeqvb2pLWC3u5J
|
|
Srylax
suggested changes
Aug 28, 2026
Review on this PR asked for services.step-agent.settings rather than a hand-written environment.etc entry, and #552 rewrites the install section around exactly that. This PR keeps only the troubleshooting wording, which is now right for every platform: smallstep/agent#1205 shipped in 0.69.3, so current deb/rpm units report ConditionPathExists= too. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
tashian
added a commit
that referenced
this pull request
Sep 15, 2026
Review pointed out that "settings is written to agent.yaml" reads as if the option writes the file in place. The module renders it into the store and links it at /etc/step-agent/agent.yaml so the daemon and the CLI find one file; say that. The edge snippet now shows 0.69.3, which is on the stable channel today but not yet in nixpkgs (0.69.2), so it is the case the section describes. Hash recomputed from the downloaded tarball and matches the manifest's sha256_sri. The troubleshooting-agent.mdx addition moves out of this PR: #549 carries the ConditionPathExists= wording now that agent#1205 shipped in 0.69.3. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs OFF-19.
smallstep/agent#1205 merged and shipped in 0.69.3, now on the stable channel, so the condition below is what current deb/rpm units and the NixOS module both report.
Why
The NixOS section told readers not to manage
agent.yamlwithenvironment.etc, because "that produces a read-only symlink into the Nix store, and the service refuses to start." The diagnosis was wrong, and the advice ruled out the deployment NixOS users actually want — a customer raised exactly this while packaging the module for nixpkgs (NixOS/nixpkgs#555971).Neither the symlink nor the file mode was the problem. The unit gated on
ConditionPathIsReadWrite=, which persystemd.unit(5)tests whether the underlying filesystem is mounted read-only — not whether the file is writable — and it resolves symlinks. NixOS remounts/nix/storeread-only at boot, so the check landed there and skipped the unit. The agent itself reads a mode 0444agent.yamlwithout complaint and never writes to it; everything it writes lives in/var/lib/step-agent.agent#1205 changes that gate to
ConditionPathExists=, the question the unit meant to ask all along.Changes
platform/smallstep-agent.mdx— no longer touched. The declarative example was dropped after review; NixOS: declare the agent with services.step-agent; document edge releases #552 documents it asservices.step-agent.settings.platform/troubleshooting-agent.mdx— update the "unmet condition check" callout to the new directive name, and note that older agents report the same check under the old one, so the message matches whichever version a reader has installed.Checks
valerun against the file before and after: no new alerts.🤖 Generated with Claude Code
https://claude.ai/code/session_01RkEcowtxSeqvb2pLWC3u5J